/*
 * Copyright (c) 2011 Obix Labs Limited
 * Redistribution and use in source and binary forms, 
 * with or without modification, are permitted provided 
 * that the following conditions are met:
 * 
 * 		Redistribution of source code must retain the above 
 * 		copyright notice, this list of conditions and the 
 * 		following disclaimer.
 *
 * 		Redistribution in binary form must reproduce the 
 * 		above copyright notice, this list of conditions 
 * 		and the following disclaimer in the documentation 
 * 		and/or other materials provided with the distribution.
 * 
 * 	THIS SOFTWARE IS PROVIDED "AS IS," WITHOUT A WARRANTY OF 
 * 	ANY KIND. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS 
 * 	AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, 
 * 	FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, 
 * 	ARE HEREBY EXCLUDED. OBIX LABS LIMITED ("Obix Labs") AND ITS 
 * 	LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE 
 * 	AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR 
 * 	ITS DERIVATIVES. IN NO EVENT WILL Obix Labs OR ITS LICENSORS BE 
 * 	LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, 
 * 	INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE 
 * 	DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF 
 * 	LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS 
 * 	SOFTWARE, EVEN IF Obix Labs HAS BEEN ADVISED OF THE POSSIBILITY OF 
 * 	SUCH DAMAGES.
 */
package com.obixlabs.commons.util;

import java.util.Set;

/**
 * <p>
 * Encapsulates a set operation such as an {@link SetIntersection intersection}.
 * </p>
 */
public abstract class SetOperator
{
	/**
	 * <p>
	 * Static reference to the {@link SetIntersection intersect} operator.
	 * </p>
	 */
	public static final SetOperator INTERSECTION = new SetIntersection();

	/**
	 * <p>
	 * Static reference to the {@link SetUnion union} operator. 
	 * </p>
	 */	
	public static final SetOperator UNION = new SetUnion();
	
	/**
	 * <p>
	 * Static reference to the {@link SetDifference difference} operator.
	 * </p>
	 */		
	public static final SetOperator DIFFERENCE = new SetDifference();
	
	
	/**
	 * <p>
	 * Applies the implemented operation to the given sets. Note that the order of the 
	 * arguments to this method is important, as one parameter forms the left side of the 
	 * set operation and the other the right side. Hence, for some operators, the results will 
	 * differ if the order of the arguments is changed. 
	 * </p>
	 * 
	 * <p>
	 * <b>Note:</b> This method accepts both null and empty parameters.
	 * </p>
	 * 
	 * @param lhs	The left-side of the set operand. For example, in the expression <i>'A-B'</i>,
	 * this parameter would correspond to the set <i>'A'</i>.
	 * @param rhs	The right-side of the set operand. For example, in the expression <i>'A-B'</i>,
	 * this parameter would correspond to the set <i>'B'</i>.
	 * 
	 * @return	The result of applying the operand to the specified sets.
	 */
	public abstract<T> Set<T> evaluate(Set<T> lhs, Set<T> rhs);
}